Skip to content

Conversation

@KrystalDelusion
Copy link
Member

@KrystalDelusion KrystalDelusion commented May 22, 2025

What are the reasons/motivation for this change?

While bugpoint is great for minimising designs there isn't much documentation on how to do that.

Explain how this is achieved.

Add a how-to guide on using bugpoint, specifically aimed at people trying to minimise failing designs whether that failure is due to Yosys or the design. This includes both a user-facing guide for minimising designs and a more developer focused guide which goes into minimising scripts (with the suggestion that people using fuzzers to find bugs should be minimising their scripts so as to avoid duplicate issues).

This also makes some additions to the Loading a design page and the contributing page which I totally forgot about until just now so they are still bullet points (though both pages already were mostly bullet points, this just adds more bullet points).

If applicable, please suggest to reviewers how they can test the change.

Check links above for preview build. Some of the content assumes changes from #5068 are included.

@KrystalDelusion
Copy link
Member Author

Added (very brief) examples for using C-Reduce and sv-bugpoint for minimizing Verilog designs.

@Ravenslofty Ravenslofty self-assigned this Aug 4, 2025
Copy link
Collaborator

@Ravenslofty Ravenslofty left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read through it; looks good to me!

How to guide for using bugpoint, minimizing yosys scripts, and minimizing verilog code.
AKA how to MVCE.
Talk about input files coming from command line, the `read` command, and features provided by `RTLIL::Frontend` (making note that `read_slang` is a subclass but `ghdl` isn't).
Also dropping the `autosectionlabel_maxdepth = 1` so that I can actually use the auto section labels.
Adds warning on bash substitution on scripting intro page when talking about `yosys -p`.
Fix error on duplicated heading.
Drop `cmd_ref`_ link (everything already uses :doc:`cmd_ref`).
Add a note on fuzzers, with a polite suggestion that if you're fuzzing you should put in the work of identifying the underlying issue so that you (and we) are confident you're not raising multiple issues for the same bug.
Was previously in yosys_internals which is more developer focused, rather than user focused.
Also some other tidy up and clarifications.
What do I do with the minimized design and (the first half of) Minimizing scripts
More info for creating GitHub issues and the different sections.
Discuss additional details that can be included as comments on the issue.  Also mention Gists for large files (preferable to downloading a .txt).
Add a warning about external plugins/tools.
Also add a note to `load_design.rst` about `Frontend`s and `-f` command line option.
I just missed that it only gets included in the makefile if `DISABLE_SPAWN` is set, because I was looking for the C define `YOSYS_DISABLE_SPAWN`.
part 2: electric boogaloo
Move `yosys -h bugpoint` failure into a code-block to break up text.  Same for the `exec -expect-return` example.
TODOs on #5068 being merged.
Move the "creating an issue" section from bugpoint.rst to "reporting bugs" in `contributing.rst`.
Fix link to `CONTRIBUTING.md`.
Update `CONTRIBUTING.md` to refer to the bugpoint guide instead of the stack overflow guide.
Minimizing scripts (and more generally identifying root cause) isn't necessary for regular bug reports.  Rather, it can be useful for developers working on *fixing* bugs, and also for fuzzers to avoid spam.
Minor adjustments to `bugpoint.rst`.
Add note to `advanced_bugpoint.rst` about primitives when minimizing scripts.
Update text to assume bugpoint PR changes.
Also fix missing double backtick.
@KrystalDelusion
Copy link
Member Author

Rebased on 0.55+150

@Ravenslofty
Copy link
Collaborator

When CI is green, merge it.

@KrystalDelusion KrystalDelusion merged commit 700ba98 into main Aug 5, 2025
48 checks passed
@KrystalDelusion KrystalDelusion deleted the docs-preview-bugpoint branch August 5, 2025 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants